TECFlushMultipleEncodings

Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 3 - Text Encoding Converter Reference / Text Encoding Converter Functions

TECFlushMultipleEncodings
Flushes out any encodings that may be stored in a converter object's temporary buffers and shifts encodings back to their default state, if any.
pascal OSStatus TECFlushMultipleEncodings(
                     TECObjectRef encodingConverter, 
                     TextPtr outputBuffer, 
                     ByteCount outputBufferLength, 
                     ByteCount *actualOutputLength, 
                     TextEncodingRun outEncodingsBuffer[], 
                     ItemCount maxOutEncodingRuns, 
                     ItemCount *actualOutEncodingRuns);
encodingConverter
The reference to the text encoding converter object whose contents are to be flushed. This is the reference returned by the function TECCreateOneToManyConverter (page 99).
outputBuffer
A pointer to a buffer for a byte stream. On return, this buffer holds the converted text. If the buffer that you allocate is not large enough to hold the entire converted text stream, an error is returned.
outputBufferLength
The length in bytes of the buffer provided by the outputBuffer parameter.
actualOutputLength
A pointer to a value of type ByteCount. On output, this value is the actual number of bytes of the converted text returned in the buffer specified by the outputBuffer parameter.
outEncodingsBuffer[]
An ordered array of text encoding runs for the destination text encoding. Note that the actual byte size of this buffer should be actualOutEncodingRuns * sizeof(TextEncodingRun). See TextEncodingRun (page 45) for more information about the TextEncodingRun structure.
maxOutEncodingRuns
The maximum number of encoding runs that will fit in outEncodingsBuffer[].
actualOutEncodingRuns
A pointer to a value of type ItemCount. On return, actualOutEncodingRuns specifies how many runs were put in the buffer during conversion.
function result
A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) for a list of possible values.

DISCUSSION
You should always call TECFlushMultipleEncodings at the end of the conversion process to flush out any data that may be stored in the temporary buffers of the text encoding converter object or perform other end-of-encoding conversion tasks. Encodings such as ISO-2022-JP that need to shift back to a certain default state at the end of a conversion can do so when this conversion function is called.
In allocating an output buffer, a good rule of thumb is larger is better, basing your estimate on the byte requirements of the destination encoding. You should always allocate a buffer at least 32 bytes long. For the function to return successfully, the output buffer you allocate must be large enough to accommodate at least part of the converted text. Then, if the function cannot convert all of the text, it executes successfully, returns the portion of the text it converted, and returns the number of source bytes it removed from input in the actualInputLength parameter. You can use this number to identify the next byte to be taken and to determine how many bytes remain. To convert the remaining text, you simply call the function again with the remaining text and a new output buffer.
If the output buffer you allocate is too small to accommodate any of the converted text, the function fails. For example, if the destination encoding requires bytes in addition to the actual text (for instance, an escape sequence preceding the converted text), your buffer must be large enough to accommodate both.

IMPORTANT
If the destination encoding is a character encoding scheme--such as ISO-2022-JP, which begins in ASCII and switches to other coded character sets through limited combinations of escape sequences--then you need to allocate enough space to accommodate escape sequences that signal switches. ISO-2022-JP requires 3 to 5 bytes for an escape sequence preceding the 1-byte or 2-byte character it introduces. If you allocate a buffer that is less than 5 bytes, the TECConvertText function could fail, depending on the text being converted.

SEE ALSO
The function TECFlushText (page 97)
The function TECCreateOneToManyConverter (page 99)